﻿/*!
 * Copyright (c), 上海沃恩信息科技有限公司.
 * All rights reserved.
 * Licensed under BSD (https://www.pittypat.work/bsd.html).
 */

using System;
using System.Threading.Tasks;

namespace Pittypat.Data
{
    /// <summary>
    /// 表示一个数据服务。数据服务可能是数据库、文件或者 Web Service 等。
    /// </summary>
    /// <remarks>
    /// <para><see cref="IDataService"/> 被一个 <see cref="Module"/> 的对象实例在内部创建和引用，用于执行数据操作任务，比如数据库操作。</para>
    /// <para>数据服务的路径由配置文件中的模块配置项目（dataServiceUrl）定义，具体参见：<see cref="Pittypat.Configuration.ModuleConfig"/>。</para>
    /// <para>
    /// <see cref="Module"/> 中的 Api 功能方法可能在不同的线程上执行，因此不应该在 <see cref="IDataService"/> 内部保存和使用线程不安全的数据，比如一个数据库连接对象。
    /// 为此，<see cref="IDataService"/> 不是一个 <see cref="IDisposable"/>，<see cref="IDataService"/> 的实现类型应该在每次 Exec 方法内部打开连接，并在执行完成后关闭连接。
    /// </para>
    /// </remarks>
    public interface IDataService
    {
        /// <summary>
        /// 在当前数据服务上异步执行指定的功能数据操作。
        /// </summary>
        /// <typeparam name="TArgs">要执行的功能的参数实体类的类型。</typeparam>
        /// <param name="model">功能模型对象，其中包含了功能的参数列表（也就是功能实体类的一个对象实例）、执行结果、结果错误消息以及当前用户等。</param>
        /// <param name="progress">跟踪和汇报异步操作的进度。如果当前请求使用了 WebSocket，可以通过该对象汇报操作进度，以便向用户显示进度条。</param>
        /// <returns>异步操作任务。</returns>
        Task Exec<TArgs>(FunctionModel<TArgs> model, IAsyncProgress progress) where TArgs : FunctionArgs, new();
    }
}
